PsL Monthly 1993 December

home *** CD-ROM | disk | FTP | other *** search

/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / cwdkit.com / CWDKIT5.DOC < prev next >

Wrap

Text File | 1988-12-08 | 20.9 KB | 476 lines

Centiwrite 1.00 Developer's Kit User's Manual ========== ==== =========== === ====== ====== Copyright 1988 Andrew M. Saucci, Jr. What's to Follow 1. Introduction 2. About the Author 3. The Interface of the Unit 4. What You'll Need to Compile 5. The Basic Principles 6. A Sample Calling Program 7. Analysis of the Sample Program 8. The Initial Values 9. Initializing the Array 10. For Extra Punch in Your Program 11. Down to Brass Tacks 12. Boilerplate 13. To All Those Who Helped 14. Coming Attractions 15. It's Alive! ============================================================================= Introduction Congratulations on having acquired this useful developer's tool. Now you can have an "instant editor" in your own programs whenever you need to include the capability to create short memos, notes, or letters. This file will attempt to show you how to incorporate the Centiwrite 1.00 editor into your Turbo Pascal programs. If you are unfamiliar with this editor, you should definitely obtain a copy of the stand-alone version of Centiwrite and read its User's Manual. This explains in detail the operation of the editor. ============================================================================= About the Author Andrew M. Saucci, Jr. was graduated with distinction from the New York Institute of Technology with a master's degree in computer science. He received a bachelor's degree in computer science from Hofstra University. The Centiwrite Developer's Kit is his first program to be distributed for programmers by commercial on-line services. Since purchasing his first personal computer, a Dell System 200, Mr. Saucci has read extensively about the IBM-compatible world of computers. Included in his personal library are The New Peter Norton Programmer's Guide to the IBM PC and PS/2, PC Magazine's DOS Power Tools, Advanced Turbo Pascal, and subscriptions to almost all major PC publications, plus some "not-so-major" newsletters and the like. Mr. Saucci can be reached at any of the following electronic mail addresses: CompuServe 72117,241 The Source BFE501 BIX ASAUCCI Genie ASAUCCI3 Delphi ASAUCCI Comments about any of his products are most welcome. ============================================================================= The Interface of the Unit unit centwri5; interface uses dos, crt; type scarray= array [1..60] of string[85]; commstruc= record screline: scarray; lastring, initWhereX, initWhereY: byte; CurAttr, StdAttr, MessAttr: byte; passkey: char; insmode: boolean; end; function nextword (sentence: string): integer; function lastword (sentence: string): integer; function datestring: string; function timestring: string; procedure AnalyzeKey (var inkey: char; var excode: boolean; var scancode: byte); procedure GetKey (var inkey: char); procedure DelWord (var sentence: string; position: integer); procedure Centiwrite (var infoexch: commstruc); implementation { Implementation would follow here. } Each of the variables used in the "commstruc" (for "communications structure" record is described below. screline: The strings which represent each line of the text to a maximum of 60. This accomodates 25-, 43-, and 50-line screens. lastring: The number of currently "valid" strings in screline. Because a line consisting solely of a carriage return (ASCII 13-10) is represented by a null string, "lastring" indicates how many lines of screline are currently being used. Note that in an empty file, lastring is 1. initWhereX: The initial x-coordinate of the cursor on entry to the editor. initWhereY: The initial y-coordinate of the cursor on entry to the editor. CurAttr: The color attribute of the cursor. You can use any valid attribute. If the foreground and background are the same, the Centiwrite editor assumes that the blinking hardware cursor is being used, and the cursor emulation is disabled. The cursor will appear as a blinking CHARACTER if a background color greater than 7 is used. StdAttr: The normal color attribute of the editor. MessAttr: The color attribute for messages which appear on the status line. passkey: The character passed back to the main program when Centiwrite does not define a function for it. insmode: If true, then the editor is in Insert mode. Otherwise, Overstrike mode is used. The functions and procedures which are included are summarized next. nextword: Returns the position of the next word in a string. In the string "for he's a jolly good fellow", nextword returns 4. If no "next word" is found, the return value is the length of the string plus 1. lastword: Returns the position of the last word in a string. In the string "which nobody can deny", lastword returns 18. If the string is a single word, the return value is 1. datestring: Returns the current system date in the form "Monday, May 26, 1988". timestring: Returns the current system time in the form "10:45:44 PM". AnalyzeKey: Substitute keyboard reading procedure (for ReadKey). A single call returns all pertinent keyboard information-- no need to make multiple calls to check for extended key codes. GetKey: Another substitute for ReadKey, but returns extended key codes as ASCII zero with a single call. DelWord: Deletes the word starting at a given location in a string. Centiwrite: The editor itself. ============================================================================= What You'll Need to Compile In order to compile a program using Centiwrite, you need to copy CENTWRI5.TPU into the directory where Turbo Pascal normally looks for your .TPU files. In version 5.0, this is one of the EXE & TPU directories specified under the Options/Directories menu selection. You will also need to add the line "uses centwri5;" to the the source file of the procedure that calls the editor. Check your Turbo Pascal manual for additional information on including units in your programs. Oh, yes, you'll also need Turbo Pascal version 5.0. For those concerned about needing to recompile for future versions of the compiler, the current plan is to update the unit whenever a new version of Turbo Pascal is released. Upgrades will be available for a modest charge. ============================================================================= The Basic Principles The Centiwrite editor is based upon an "array of strings" implementation. While not suitable for a large text editor or word processor, this approach is quite adequate for a simple program such as this. It allows a "quick and dirty" style, and is easily understandable. Each element in the array of strings represents a line of text on the screen. An "implied" carriage return ends each line. A count of the current number of lines is maintained at all times. A duplicate array is maintained in memory in order to facilitate the "Undo" feature (invoked by F3). Some may wonder why the video memory is not used to store the text, considering that the text is stored there anyway. Use of character strings allows the use of Turbo Pascal's string-handling procedures. Using video memory would mean writing substantially more code in order to duplicate the functions already available in the runtime library. This code would not only make the program larger, but would also need to be debugged. The Turbo Pascal string-handling routines (while not perfect) are already thoroughly debugged. ============================================================================= A Sample Calling Procedure The following program is an example of how to call the editor. program CallEditor (input, output); uses dos, crt, centwri5; var origreg, reg: registers; cwinfo: commstruc; i: byte; procedure SaveFile; begin writeln ('Code for saving a file would be here.'); end; procedure HelpProcedure; begin writeln ('Help! Help!'); end; begin origreg.ah:= $03; origreg.bh:= $00; intr ($10, origreg); { Save old cursor } reg.ah:= $01; reg.ch:= $20; reg.cl:= $00; intr ($10, reg); { Disable hardware cursor } with cwinfo do { Allows unqualified variable references. } begin insmode:= true; { Initialize structure variables. } initWhereX:= 1; initWhereY:= 1; CurAttr:= $5F; { White on Cyan } StdAttr:= $17; { LightGray on Blue } MessAttr:= $20; { Black on Green } for i:= 1 to 25 do screline[i]:= ''; { empty file } lastring:= 1; repeat window (1, 1, 80, 25); TextAttr:= $07; ClrScr; writeln ('Joe''s Program: Centiwrite Editor-- Alt-X to Exit'); window (1, 2, 80, 25); Centiwrite (cwinfo); { <------------- PLUG-IN EDITOR } window (1, 1, 80, 25); TextAttr:= $07; if (passkey= #45) or (passkey= #60) { If Alt-X or F2, save the file. } then SaveFile; if passkey=#59 { F1 displays a list of keys and their functions. } then HelpProcedure; until ((passkey=#32) or (passkey=#45)); { Alt-D or Alt-X (exit condition) } end; { with statement } ClrScr; origreg.ah:= $01; intr ($10, origreg); { restore cursor } end. { program } ============================================================================= Analysis of the Sample Program Take a close look at the sample program. Although it has been simplified in order to highlight the main points, its basic structure is the same as that of the stand-alone version of Centiwrite 1.00. It gives initial values to the members of the structure, and then runs the editor in a repeat..until loop. Why a loop? This is the means you can use to add your own "frills" to the editor. Any time the Centiwrite editor sees a key that it does not recognize, such as F6, Alt-Z, or Ctrl-F5, the editor terminates and control returns to the calling procedure. Placing the editor in a loop gives you a chance to execute whatever procedures or functions you like before RETURNING control, or exiting if you like. For example, Alt-X is the "recommended" exit key. The editor takes no special action on seeing Alt-X; it merely exits just the same as it would for any other unrecognized key. The "until" condition "passkey=#45" is what causes the sample program to terminate. To use F10 as an exit key, just change the condition to "passkey=#68". Likewise, what displays help is "passkey=#59"; to use Shift-F1, change to "passkey=#84". Note that the editor recognizes all keys that return an ASCII value plus the following extended keys: arrow keys Shift-Tab Ctrl-Left arrow Alt- B E T Y H V Insert Home/End Ctrl-Right arrow F3 F5 F7 F8 Delete Ctrl-Home/End Ctrl-F8 The calling procedure is passed any other keys and may deal with them however it sees fit. The value passed back to the calling procedure is the extended value of the last key pressed. An "extended" flag is not necessary because only extended key codes can be returned. If you need to intercept any values which are normally recognized by the editor, you must either write an interrupt $09 or $16 handler that "grabs" the values you want or obtain a customized version of CENTWRI5.TPU that passes the keys you need. (This is available for an additional charge.) Notice the "window" statement just before the call to Centiwrite. This is absolutely necessary in order for the editor to establish its window boundaries and insure the integrity of its screen. The editor can operate in a window no narrower than 40 columns. It has not been tested in windows shorter than 24 rows; however, it should work for any number of rows greater than three, which is the minimum. (For a single row "window" you should use "liminput", the complete source code to which is found in the Deciwrite Developer's Kit.) If you specify a window size of fewer than 40 columns, greater than the screen width, or greater than the screen height, the result is unknown. The Centiwrite editor redraws its window each time it is called, and it leaves the screen in place when it exits. Therefore, you can put a window over it without any trouble. ============================================================================ The Initial Values The most important value in "commstruc" is "lastring". If you use an invalid value for lastring, the editor will become confused and behave erratically. Lastring should be 1 for an empty file. Otherwise, it reflects the number of currently valid strings in the array "screline". Example. If screline is this (line numbers added): [1] Now is the time for all good people. [2] We must mobilize now. [3] [4] May we have your support? then lastring is 4. If two carriage returns are added after line 4, as in [4] May we have your support? [5] [6] then lastring is 6. Lastring should only be changed when the number of lines in the text is changed. Here's an important note about carriage returns. The Centiwrite editor does NOT add the ASCII 13-10 combination explicitly to the text. Every string ends in an IMPLIED 13-10. If you write a file to disk, you must add the 13-10 yourself. This is easily done using a "writeln(screline[i])"-type statement. You need not delete a 13-10 on input, however, as the editor automatically removes these (as well as ASCII 7 and 8) from the text. You should, however, take care to format the input strings so that they do not contain embedded carriage returns that really belong at the end of a line. InitWhereX and initWhereY are used to position the cursor when the editor is called. For the first invocation, each of these should usually be set to 1, although any valid values are acceptable. Never position the cursor below the row "lastring", or erratic operation will result. When the editor passes control back to the calling procedure, the current cursor position is saved in initWhereX and initWhereY. It can then be reused if necessary when the editor is called again. Pressing F6 demonstrates this simply. The cursor position is saved; the editor returns control to the main program; the main program ignores the key (because no function has been defined for it there, either); and the editor regains control, positioning the cursor at the saved location. Insmode, as explained earlier, is simply a flag. It's your choice-- set it however you like depending upon whether you want to start the editor in Insert mode or Overstrike mode. Passkey need not be initialized. It is strictly a return value. ============================================================================ Initializing the Array You must initialize "screline" before using it. This can be done any way you like-- with assignment statements, reads, etc. You should assign an initial value to "maxline" elements in screline, where "maxline" is equal to the maximum number of lines on the screen plus 1. Be sure to keep "lastring" synchronized with the actual number of elements of screline in use. ============================================================================= For Extra Punch in Your Program If you want to use a "plug-in editor" in your program, but feel Centiwrite just isn't powerful enough, don't walk away feeling dejected. Here's good news! Also available is an editor similar to Centiwrite but ten times as powerful. It's Deciwrite! The Deciwrite Developer's Kit includes all the features of Centiwrite PLUS: 1. Automatic word wrap and paragraph reformatting. 2. Full support for binary files. 3. Time and date can be inserted into the text with one keystroke. 4. Full source code-- including liminput, a replacement for readln; dectohex and hextodec, hexadecimal conversion routines; and FileCheck, which checks for the existence of a file and determines if it is read-only; and more! What's more, if you're not sure, you can "lock in" the price of the Deciwrite Developer's Kit by buying the Centiwrite Developer's Kit NOW. You'll have one year to upgrade at the current price, PLUS you get a credit for what you paid for the Centiwrite Developer's Kit. What's to lose? Send electronic mail to the addresses listed earlier to learn how to take advantage of this great offer. ============================================================================= Down to Brass Tacks As of December 1, 1988, this is the Centiwrite/Deciwrite price list. Individual License Site License Centiwrite 1.00 $12.50 $200.00 Deciwrite 1.00 $25.00 $400.00 Centiwrite 1.00 Developer's Kit For Turbo Pascal 4.0 $22.50 $350.00 For Turbo Pascal 5.0 $27.50 $450.00 Upgrade to 5.0 $ 7.50 $120.00 Deciwrite 1.00 Developer's Kit $60.00 $900.00 Disk replacement fee $ 2.50 none New York State residents must add their local sales tax. Residents of other states will in most cases be required to remit the appropriate tax directly to their state tax department. An individual license permits the user to operate the program on a single computer at a time, while a site license permits unlimited use within the confines of a contiguous area of the owner's property. These prices are guaranteed not to increase through April 1, 1989. Custom implementations of these programs are also available on request for modest additional fees. Send electronic mail to one of the addresses listed earlier. At this time, credit cards cannot be accepted. Make checks payable to Andrew M. Saucci, Jr. 727 Barkley Ave East Meadow, NY 11554-4502. Please specify the disk size you require. You may wish to check one of the electronic mail addresses to verify that the above address is current. Please use this "physical" address ONLY for orders. All other correspondence, including technical support questions, should be directed to one of the electronic mail addresses. ============================================================================ Boilerplate Liability in the event of defects in Centiwrite 1.00 and/or the Centiwrite 1.00 Developer's Kit is expressly limited to replacement of the disk on which Centiwrite and/or the Developer's Kit was originally provided. No other liability of any sort is either implied or assumed. In particular, the user is responsible for all consequential damages, such as loss of income, loss of data, pain and suffering, etc. ============================================================================ To All Those Who Helped Thanks to all those who gave their assistance toward the completion of this program, especially Michael Day, Neil Rubenking, Scott Bussinger, and all the other helpful people who frequent Borland's Programming Forum A (BPROGA) on CompuServe. It's truly amazing! ============================================================================ Coming Attractions A plan to produce a full-size text editor based on Centiwrite and Deciwrite is in the works. Please use Centiwrite to write a short note describing a few of the features you would like to see in a text editor, particularly anything that is not found in other programs, and send it to one of the electronic mail addresses. The result could be a really good program. You might also indicate what incentives are most likely to cause you to purchase registered copies of programs distributed on a "try-before-you-buy" basis. Your suggestions will be most appreciated. ============================================================================ It's Alive! This program is not carved in stone. Many of you no doubt have extensive experience in this field, and your comments and suggestions are valuable and welcome. Send them to the electronic mail addresses listed. ============================= END OF FILE ===================================